<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<link rel="stylesheet" type="text/css" href="rotor.css">
<title>Shared Source CLI Directory Layout Overview</title>
</head>
<body>

<h1>Shared Source CLI 2.0 Directory Layout Overview</h1>
<p>This document discusses the layout of  the Microsoft&reg; 
Shared Source CLI (SSCLI) 2.0 distribution.</p>

<h3>Important Note on Licensing</h3>

<blockquote>

<p><font color="#FF0000"><b>Before you proceed with building the Shared Source CLI you should carefully review the 
license.</b></font></p>

</blockquote>

<p>The file named <a href="../license.txt">license.txt</a> contains the 
Microsoft Shared Source CLI/JScript/C# License, which applies to this entire 
distribution. The file named
<a href="../license_banner_for_sources.txt">license_banner_for_sources.txt</a>
is the copyright banner that is injected into most of the files found in this
distribution.  A few files in this distribution  are licensed under other licenses, and 
Microsoft has preserved the copyright
and license notices for these. </p>

<h3><a href="../">sscli20</a> is the top-level directory</h3>


<p>
To build the SSCLI, you must be running within
a command window in Microsoft Windows&reg;.
The build procedure is detailed in the document
<a href="buildtools/building_sscli.html">building_sscli.html</a>; but to summarize,
you first set up your environment by running one of the  env scripts with one of 
the build options (checked, debug, or free) and then run the buildall.bat batch file.&nbsp;
</p>

<p>
Key files in this directory:
<ul>
<li>license.txt and license_banner_for_sources.txt</li>
<li> env.bat</li><li> buildall.cmd</li>
<li>readfirst.html</li>
</ul>

<h3>
    sscli20/binaries.x86*.rotor contains build binary output</h3>

<p>
This directory is generated during the build process and contains the build 
output, including managed and unmanaged executables
and shared dynamic link libraries and class libraries, as well as  debugging symbols and the directory
used as the global assembly cache.&nbsp; Note that some core build output can be 
found in the sscli20/binaries.x86*.rotor
    root directory, while tools are mostly in sdk/bin 
directory.</p>

<p>
Each target that you build (debug, checked, or free) will generate a 
separate 
set of build output subdirectories. The "*" character will be replaced with "dbg" on
    debug builds, "chk" on checked builds and "fre" on free builds.</p>

<blockquote>

<p>
Note: The sscli20/binaries.x86*.rotor directory will only exist after a build has completed.</p>

</blockquote>

<h3><a href="../clr/src">sscli20/clr/src</a> contains the core CLI and base class 
library implementations</h3>

<p>
The sscli20/clr/src directory contains a substantial amount of the CLI and all the 
base class library code.&nbsp;The following table contains a detailed description of the key subdirectories.<br>
&nbsp;

<table border="1" width="90%">
  <tr valign="top">
    <th width="30%">Subdirectory</th>
    <th width="70%">Subdirectory Description</th>
  </tr>
  <tr valign="top">
    <td width="30%">
<a href="../clr/src/vm">vm</a> subdirectory</td>
    <td width="70%">Contains the bulk of the CLI core implementation, including the garbage 
collector, the class loader, the type system, error reporting, application 
    domains, 
assemblies, delegate support, reflection, security, and the code manager.  
    <p>The vm subdirectory contains numerous valuable files to review. (For those curious about the 
build process, note that vm has a <code>dirs</code> file, but the <code>sources</code> file can be found 
in the vm/wks subdirectory.) </td>
  </tr>
  <tr valign="top">
    <td width="30%">
<a href="../clr/src/csharp">csharp</a> subdirectory</td>
    <td width="70%">Contains the sources for the C# compiler (csc.exe) and the 
    Assembly Linker. </td>
  </tr>
    <tr valign="top">
        <td width="30%">
            <a href="../clr/src/classlibnative">classlibnative</a> subdirectory</td>
        <td width="70%">
            Contains common types and internationalization routines.</td>
    </tr>
    <tr valign="top">
        <td width="30%">
            <a href="../clr/src/dacupdatedll">dacupdatedll</a> subdirectory</td>
        <td width="70%">
            Build scripts to autogenerate tables describing layout for the SOS debugger extension.</td>
    </tr>
    <tr valign="top">
        <td width="30%">
            <a href="../clr/src/jit64">jit64</a> subdirectory</td>
        <td width="70%">
            Contains the source for the implementation of the standalone verifier. Sorry, no
            actual 64bit JIT here.</td>
    </tr>
    <tr valign="top">
        <td width="30%">
            <a href="../clr/src/inc">inc</a> subdirectory</td>
        <td width="70%">
            Common include files.</td>
    </tr>
    <tr valign="top">
        <td width="30%">
            <a href="../clr/src/ipcman">ipcman</a> subdirectory</td>
        <td width="70%">
            Contains the sources for interprocess communication.</td>
    </tr>
    <tr valign="top">
        <td width="30%">
            <a href="../clr/src/managedlibraries">managedlibraries</a> subdirectory</td>
        <td width="70%">
            Contains source for remoting and the soapserializer.</td>
    </tr>
  <tr valign="top">
    <td width="30%"><a href="../clr/src/utilcode">utilcode</a> subdirectory</td>
    <td width="70%">Contains core routines used throughout the runtime, the 
    tools, and the C# compiler. 
    <p>Includes code for path handling and parsing, array and hashtable 
    management, C runtime routines, character case support, library and assembly 
    loading, debugging and logging instrumentation, and synchronization, as well as 
    utility code for many miscellaneous tasks such as formatting, GUID creation, 
    error handling, and registry and configuration access. </td>
  </tr>
  <tr valign="top">
    <td width="30%"><a href="../clr/src/md">md</a> subdirectory</td>
    <td width="70%">Contains a metadata reader and writer.</td>
  </tr>
  <tr valign="top">
    <td width="30%"><a href="../clr/src/fjit">fjit</a> subdirectory</td>
    <td width="70%">Contains the SSCLI JIT compiler and its verifier.</td>
  </tr>
  <tr valign="top">
    <td width="30%"><a href="../clr/src/fusion">fusion</a> subdirectory</td>
    <td width="70%">Contains code that implements binding to assemblies, policy checking for the binding 
process, and the global assembly cache.</td>
  </tr>
  <tr valign="top">
    <td width="30%"><a href="../clr/src/bcl">bcl</a> subdirectory</td>
    <td width="70%">Contains C# code for the ECMA base class libraries. 
Most of the interesting code is in <a href="../clr/src/bcl/system">system</a>
and its sub-directories. </td>
  </tr>
  <tr valign="top">
    <td width="30%"><a href="../clr/src/debug">debug</a> subdirectory</td>
    <td width="70%">Contains the source code for the Runtime Debugger.</td>
  </tr>
  <tr valign="top">
    <td width="30%"><a href="../clr/src/ilasm">ilasm</a> subdirectory</td>
    <td width="70%">Contains the source code for the CIL Assembler. </td>
  </tr>
  <tr valign="top">
    <td width="30%"><a href="../clr/src/ildasm">ildasm</a> subdirectory</td>
    <td width="70%">Contains the source code for the CIL Disassembler. </td>
  </tr>
  <tr valign="top">
    <td width="30%"><a href="../clr/src/tools">tools</a> subdirectory</td>
    <td width="70%">Contains source code for the PEVerify tool, a managed code 
    launch tool (clix.exe), a metadata dump tool (metainfo.exe), a reader/writer 
    for managed debugger symbols, and numerous other tools. </td>
  </tr>
    <tr valign="top">
        <td width="30%">
            <a href="../clr/src/toolbox">toolbox</a> subdirectory</td>
        <td width="70%">
            Contains source code for caspol, strike and other tools.</td>
    </tr>
  <tr valign="top">
    <td width="30%"><a href="../clr/src/dlls">dlls</a> subdirectory</td>
    <td width="70%">Contains subdirectories for all of the native 
    shared libraries that are linked as a part of the build process.
    <p>These directories are useful for utility functions for building tools.</td>
  </tr>
    <tr valign="top">
        <td width="30%">
            <a href="../clr/src/xmlparser">xmlparser</a> subdirectory</td>
        <td width="70%">
            Contains source for the XML parser.</td>
    </tr>
</table>


<h3><a href="../docs">sscli20/docs</a> is documentation for the Shared Source CLI</h3>

<p>
The sscli20/docs directory contains the documentation for the SSCLI.</p>

<p>
Some points of interest in this directory:</p>

<ul>
  <li>relnotes.html - release notes.</li>
  <li>testing_overview.html - overview of the testing infrastructure.</li>
  <li>glossary.html - glossary of terms used in the documentation and source 
  code.</li>
  <li>index.html - index of documentation.</li>
</ul>

<p>
The subdirectories contain additional documentation.&nbsp; See the index.html 
for the full details.</p>

<h3><a href="../fx/src">sscli20/fx/src</a> contains C# code that implements 
fundamental 
managed class libraries</h3>

<p>
The sscli20/fx/src directory contains several subdirectories with implementations of major namespaces,
such as regular expression support, XML support, and networking. There
is also code in the subdirectories for other miscellaneous features.
</p>

<h3><a href="../jscript/engine">sscli20/jscript/engine</a> contains the sources for a JScript compiler</h3>

<p>
The JScript compiler is  written entirely in C#, so it is interesting both
as an example of a large C# project and as an example of how to compile against
the CLI intermediate language.  The compiler uses the <b>System.Reflection</b> classes
extensively in producing its managed executable output.  JScript is also a very

dynamic language, and as such, demonstrates many useful compiler techniques
for generating CIL and runtime structures on the fly.
</p>

<h3><a href="../pal">sscli20/pal</a> contains implementations of the Platform Adaptation Layer (PAL)</h3>

<p>
Within the pal subdirectory there are two subdirectories,
<a href="../pal/unix">unix</a> and <a href="../pal/win32">win32</a>. The unix 
directory contains the implementation of the  PAL for UNIX system-based platforms and, logically enough,
the  win32 directory contains the Windows PAL. There is also an important header 
file,
<a href="../pal/inc/rotor_pal.h">rotor_pal.h</a>, which declares all of the APIs
that a developer building a new PAL would have to implement.  See
the <a href="techinfo/pal_guide.html">PAL Specification</a> for more
details on this topic.
</p>

<p>
The Win32 PAL is primarily a thin wrapper over the underlying Win32 API with 
some  logging and  parameter-checking functionality in some cases. The code 
for doing portable exception handling (in <a href="../pal/win32/exception.c">
exception.c</a>) might be useful to read.</p>

<p>
The PAL for UNIX system-based platforms, on the other hand, contains a 
substantial amount of significant code.&nbsp; This code serves to map from Win32 
API calls into equivalent functionality on UNIX system-based platforms where 
this exists, or implements that functionality where 
it does not exist.&nbsp; Some examples of the mapping work include Unicode support, 
exception handling, memory-mapped files, debugger support, sockets, and file I/O 
as well as other core functionality.</p>

<h3><a href="../palrt/src">sscli20/palrt/src</a> contains the implementation of the 
PAL runtime</h3>

<p>
To make life simpler for developers who wish to create new PAL 
implementations, some of the more generic or reusable implementation details 
have been split out into a separate library, called the PAL runtime.&nbsp; Even 
if you are
not implementing a PAL the sscli20/palrt/src directory still might be of interest because it
contains a number of useful odds and ends, including:
</p>
<ul>
<li>Implementation of the simple COM APIs used in SSCLI.</li>
<li>Cryptographic code used to support strong names and the CLI.</li>
<li>C runtime functions.</li>
<li>Math and decimal math routines.</li>
<li>Support for streaming over memory.</li>
<li>String, URL, and path name parsing and manipulation.</li>
<li>Configuration and resource loading.</li>
<li>Code used when calling from platform-native code to managed code.</li>
</ul>


<p>
The PAL runtime is used by the  PAL on UNIX system-based platforms. Note the  reduced set of
Windows header files in <a href="../palrt/inc">sscli20/palrt/inc</a> subdirectory;
these are included in order to pull in these API helpers.  If you wish
to implement a new PAL, you will probably want to use the same technique.
</p>

<h3><a href="../samples">sscli20/samples</a> contains source code for samples</h3>

<p>The sscli20/samples directory contains  samples that demonstrate SSCLI functionality.</p>

<h3><a href="../tests">sscli20/tests</a> contains numerous  tests and test suites</h3>

<p>
The sscli20/tests directory contains a large number of small tests that can be
used, once you have built the sources, to
avoid regressions while modifying the code.  The file
<a href="../tests/rrun.pl">rrun.pl</a> is a Perl driver containing useful comments
embedded within it that can be used to run the tests for the runtime itself,
while the <a href="../tests/palsuite">palsuite</a> subdirectory contains
tests for the  PAL implementation for UNIX system-based platforms.
</p>

<h3><a href="../tools">sscli20/tools</a> contains source code for portable build tools</h3>

<p>
Once a PAL has been created, using the native tool chain for whatever platform
is being built, a set of portable build tools are then built against the PAL.
This is the bootstrap that enables the bulk of the build process; these tools
use the PAL APIs to accomplish their work.  Documentation for all of these
tools can be found in the <a href="buildtools">sscli20/docs/buildtools</a> directory; see in particular
build.exe, binplace.exe, and nmake.exe.
</p>


<p><i>Copyright (c) 2006 Microsoft Corporation. All rights reserved.</i></p>
</body>
</html>
